home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / sgegv.z / sgegv
Text File  |  1996-03-14  |  10KB  |  265 lines

  1.  
  2.  
  3.  
  4. SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))                                                            SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SGEGV - compute for a pair of n-by-n real nonsymmetric matrices A and B,
  10.      the generalized eigenvalues (alphar +/- alphai*i, beta), and optionally,
  11.      the left and/or right generalized eigenvectors (VL and VR)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE SGEGV( JOBVL, JOBVR, N, A, LDA, B, LDB, ALPHAR, ALPHAI, BETA,
  15.                        VL, LDVL, VR, LDVR, WORK, LWORK, INFO )
  16.  
  17.          CHARACTER     JOBVL, JOBVR
  18.  
  19.          INTEGER       INFO, LDA, LDB, LDVL, LDVR, LWORK, N
  20.  
  21.          REAL          A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B( LDB, * ),
  22.                        BETA( * ), VL( LDVL, * ), VR( LDVR, * ), WORK( * )
  23.  
  24. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  25.      SGEGV computes for a pair of n-by-n real nonsymmetric matrices A and B,
  26.      the generalized eigenvalues (alphar +/- alphai*i, beta), and optionally,
  27.      the left and/or right generalized eigenvectors (VL and VR).
  28.  
  29.      A generalized eigenvalue for a pair of matrices (A,B) is, roughly
  30.      speaking, a scalar w or a ratio  alpha/beta = w, such that  A - w*B is
  31.      singular.  It is usually represented as the pair (alpha,beta), as there
  32.      is a reasonable interpretation for beta=0, and even for both being zero.
  33.      A good beginning reference is the book, "Matrix Computations", by G.
  34.      Golub & C. van Loan (Johns Hopkins U. Press)
  35.  
  36.      A right generalized eigenvector corresponding to a generalized eigenvalue
  37.      w  for a pair of matrices (A,B) is a vector  r  such that  (A - w B) r =
  38.      0 .  A left generalized eigenvector is a vector l such that l**H * (A - w
  39.      B) = 0, where l**H is the
  40.      conjugate-transpose of l.
  41.  
  42.      Note: this routine performs "full balancing" on A and B -- see "Further
  43.      Details", below.
  44.  
  45. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  46.      JOBVL   (input) CHARACTER*1
  47.              = 'N':  do not compute the left generalized eigenvectors;
  48.              = 'V':  compute the left generalized eigenvectors.
  49.  
  50.      JOBVR   (input) CHARACTER*1
  51.              = 'N':  do not compute the right generalized eigenvectors;
  52.              = 'V':  compute the right generalized eigenvectors.
  53.  
  54.      N       (input) INTEGER
  55.              The order of the matrices A, B, VL, and VR.  N >= 0.
  56.  
  57.      A       (input/output) REAL array, dimension (LDA, N)
  58.              On entry, the first of the pair of matrices whose generalized
  59.              eigenvalues and (optionally) generalized eigenvectors are to be
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))                                                            SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))
  71.  
  72.  
  73.  
  74.              computed.  On exit, the contents will have been destroyed.  (For
  75.              a description of the contents of A on exit, see "Further
  76.              Details", below.)
  77.  
  78.      LDA     (input) INTEGER
  79.              The leading dimension of A.  LDA >= max(1,N).
  80.  
  81.      B       (input/output) REAL array, dimension (LDB, N)
  82.              On entry, the second of the pair of matrices whose generalized
  83.              eigenvalues and (optionally) generalized eigenvectors are to be
  84.              computed.  On exit, the contents will have been destroyed.  (For
  85.              a description of the contents of B on exit, see "Further
  86.              Details", below.)
  87.  
  88.      LDB     (input) INTEGER
  89.              The leading dimension of B.  LDB >= max(1,N).
  90.  
  91.      ALPHAR  (output) REAL array, dimension (N)
  92.              ALPHAI  (output) REAL array, dimension (N) BETA    (output) REAL
  93.              array, dimension (N) On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j),
  94.              j=1,...,N, will be the generalized eigenvalues.  If ALPHAI(j) is
  95.              zero, then the j-th eigenvalue is real; if positive, then the j-
  96.              th and (j+1)-st eigenvalues are a complex conjugate pair, with
  97.              ALPHAI(j+1) negative.
  98.  
  99.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  100.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  101.              the user should avoid naively computing the ratio alpha/beta.
  102.              However, ALPHAR and ALPHAI will be always less than and usually
  103.              comparable with norm(A) in magnitude, and BETA always less than
  104.              and usually comparable with norm(B).
  105.  
  106.      VL      (output) REAL array, dimension (LDVL,N)
  107.              If JOBVL = 'V', the left generalized eigenvectors.  (See
  108.              "Purpose", above.)  Real eigenvectors take one column, complex
  109.              take two columns, the first for the real part and the second for
  110.              the imaginary part.  Complex eigenvectors correspond to an
  111.              eigenvalue with positive imaginary part.  Each eigenvector will
  112.              be scaled so the largest component will have abs(real part) +
  113.              abs(imag. part) = 1, *except* that for eigenvalues with
  114.              alpha=beta=0, a zero vector will be returned as the corresponding
  115.              eigenvector.  Not referenced if JOBVL = 'N'.
  116.  
  117.      LDVL    (input) INTEGER
  118.              The leading dimension of the matrix VL. LDVL >= 1, and if JOBVL =
  119.              'V', LDVL >= N.
  120.  
  121.      VR      (output) REAL array, dimension (LDVR,N)
  122.              If JOBVL = 'V', the right generalized eigenvectors.  (See
  123.              "Purpose", above.)  Real eigenvectors take one column, complex
  124.              take two columns, the first for the real part and the second for
  125.              the imaginary part.  Complex eigenvectors correspond to an
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))                                                            SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))
  137.  
  138.  
  139.  
  140.              eigenvalue with positive imaginary part.  Each eigenvector will
  141.              be scaled so the largest component will have abs(real part) +
  142.              abs(imag. part) = 1, *except* that for eigenvalues with
  143.              alpha=beta=0, a zero vector will be returned as the corresponding
  144.              eigenvector.  Not referenced if JOBVR = 'N'.
  145.  
  146.      LDVR    (input) INTEGER
  147.              The leading dimension of the matrix VR. LDVR >= 1, and if JOBVR =
  148.              'V', LDVR >= N.
  149.  
  150.      WORK    (workspace/output) REAL array, dimension (LWORK)
  151.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  152.  
  153.      LWORK   (input) INTEGER
  154.              The dimension of the array WORK.  LWORK >= max(1,8*N).  For good
  155.              performance, LWORK must generally be larger.  To compute the
  156.              optimal value of LWORK, call ILAENV to get blocksizes (for
  157.              SGEQRF, SORMQR, and SORGQR.)  Then compute:  NB  -- MAX of the
  158.              blocksizes for SGEQRF, SORMQR, and SORGQR; The optimal LWORK is:
  159.              2*N + MAX( 6*N, N*(NB+1) ).
  160.  
  161.      INFO    (output) INTEGER
  162.              = 0:  successful exit
  163.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  164.              = 1,...,N:  The QZ iteration failed.  No eigenvectors have been
  165.              calculated, but ALPHAR(j), ALPHAI(j), and BETA(j) should be
  166.              correct for j=INFO+1,...,N.  > N:  errors that usually indicate
  167.              LAPACK problems:
  168.              =N+1: error return from SGGBAL
  169.              =N+2: error return from SGEQRF
  170.              =N+3: error return from SORMQR
  171.              =N+4: error return from SORGQR
  172.              =N+5: error return from SGGHRD
  173.              =N+6: error return from SHGEQZ (other than failed iteration)
  174.              =N+7: error return from STGEVC
  175.              =N+8: error return from SGGBAK (computing VL)
  176.              =N+9: error return from SGGBAK (computing VR)
  177.              =N+10: error return from SLASCL (various calls)
  178.  
  179. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  180.      Balancing
  181.      ---------
  182.  
  183.      This driver calls SGGBAL to both permute and scale rows and columns of A
  184.      and B.  The permutations PL and PR are chosen so that PL*A*PR and PL*B*R
  185.      will be upper triangular except for the diagonal blocks A(i:j,i:j) and
  186.      B(i:j,i:j), with i and j as close together as possible.  The diagonal
  187.      scaling matrices DL and DR are chosen so that the pair  DL*PL*A*PR*DR,
  188.      DL*PL*B*PR*DR have elements close to one (except for the elements that
  189.      start out zero.)
  190.  
  191.      After the eigenvalues and eigenvectors of the balanced matrices have been
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))                                                            SSSSGGGGEEEEGGGGVVVV((((3333FFFF))))
  203.  
  204.  
  205.  
  206.      computed, SGGBAK transforms the eigenvectors back to what they would have
  207.      been (in perfect arithmetic) if they had not been balanced.
  208.  
  209.      Contents of A and B on Exit
  210.      -------- -- - --- - -- ----
  211.  
  212.      If any eigenvectors are computed (either JOBVL='V' or JOBVR='V' or both),
  213.      then on exit the arrays A and B will contain the real Schur form[*] of
  214.      the "balanced" versions of A and B.  If no eigenvectors are computed,
  215.      then only the diagonal blocks will be correct.
  216.  
  217.      [*] See SHGEQZ, SGEGS, or read the book "Matrix Computations",
  218.          by Golub & van Loan, pub. by Johns Hopkins U. Press.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.